Inside Macintosh: Memory
You can use the NewHandle function to allocate a relocatable block of memory, or the NewEmptyHandle function to allocate handles for which you do not yet need blocks of memory. If you want to allocate new blocks of memory in the system heap or with their bits precleared to 0, you can use the functions NewHandleSys , NewHandleClear , and NewHandleSysClear .
You should not call any of these memory-allocation routines at interrupt time.<36pt>
You can use the DisposeHandle procedure to free relocatable blocks of memory you have allocated.
You can use the NewHandle function to allocate a relocatable memory block of a specified size.
FUNCTION NewHandle (logicalSize: Size): Handle;
The NewHandle function attempts to allocate a new relocatable block in the current heap zone with a logical size of logicalSize bytes and then return a handle to the block. The new block is unlocked and unpurgeable. If NewHandle cannot allocate a block of the requested size, it returns NIL .
Do not try to manufacture your own handles without this function by simply assigning the address of a variable of type Ptr to a variable of type Handle . The resulting "fake handle" would not reference a relocatable block and could cause a system crash.
The NewHandle function pursues all available avenues to create a block of the requested size, including compacting the heap zone, increasing its size, and purging blocks from it. If all of these techniques fail and the heap zone has a grow-zone function installed, NewHandle calls the function. Then NewHandle tries again to free the necessary amount of memory, once more compacting and purging the heap zone if necessary. If memory still cannot be allocated, NewHandle calls the grow-zone function again, unless that function had returned 0, in which case NewHandle gives up and returns NIL .
Because NewHandle allocates memory, you should not call it at interrupt time.
The registers on entry and exit for NewHandle are
Registers on exit |
|
|---|---|
You can specify that the NewHandle function apply to the system heap zone instead of the current zone by setting bit 10 of the routine trap word. In most development systems, you can do this by supplying the word SYS as the second argument to the routine macro, as follows:
_NewHandle ,SYS
If you want to clear the bytes of a block of memory to 0 when you allocate it with the NewHandle function, set bit 9 of the routine trap word. You can usually do this by supplying the word CLEAR as the second argument to the routine macro, as follows:
_NewHandle ,CLEAR
You can combine SYS and CLEAR in the same macro call, but SYS must come first.
_NewHandle ,SYS,CLEAR
If you allocate a relocatable block that you plan to lock for long periods of time, you can prevent heap fragmentation by allocating the block as low as possible in the heap zone. To do this, see the description of the ReserveMem procedure on ReserveMem .
If you plan to lock a relocatable block for short periods of time, you might want to move it to the top of the heap zone to prevent heap fragmentation. For more information, see the description of the MoveHHi procedure on MoveHHi .
You can use the NewHandleSys function to allocate a relocatable block of memory of a specified size in the system heap.
FUNCTION NewHandleSys (logicalSize: Size): Handle;
You can use the NewHandleClear function to allocate prezeroed memory in a relocatable block of a specified size.
FUNCTION NewHandleClear (logicalSize: Size): Handle;
The NewHandleClear function works much as the NewHandle function does but sets all bytes in the new block to 0 instead of leaving the contents of the block undefined.
Currently, NewHandleClear clears the block one byte at a time. For a large block, it might be faster to clear the block manually a long word at a time.
You can use the NewHandleSysClear function to allocate, in the system heap, prezeroed memory in a relocatable block of a specified size.
FUNCTION NewHandleSysClear (logicalSize: Size): Handle;
The NewHandleSysClear function works much as the NewHandleClear function does, but attempts to allocate the requested block in the system heap zone instead of in the current heap zone. NewHandleSysClear sets all bytes in the new block to 0 instead of leaving the contents of the block undefined.
If you want to initialize a handle but not allocate any space for it, use the NewEmptyHandle function. The Resource Manager uses this function extensively, but you probably won't need to use it.
FUNCTION NewEmptyHandle: Handle;
The NewEmptyHandle function initializes a new handle by allocating a master pointer for it, but it does not allocate any memory for the handle to control. NewEmptyHandle sets the handle's master pointer to NIL .
Because NewEmptyHandle might need to call the MoreMasters procedure to allocate new master pointers, it might allocate memory. Thus, you should not call NewEmptyHandle at interrupt time.
The registers on exit for NewEmptyHandle are
You can specify that the NewEmptyHandle function apply to the system heap zone instead of the current zone. To do so, set bit 10 of the routine trap word. In most development systems, you can do this by supplying the word SYS as the second argument to the routine macro, as follows:
_NewEmptyHandle ,SYS
When you want to allocate memory for the empty handle, use the ReallocateHandle procedure, described on ReallocateHandle .
If you want to initialize a handle in the system heap but not allocate any space for it, use the NewEmptyHandleSys function. The Resource Manager uses this function extensively, but you probably won't need to use it.
FUNCTION NewEmptyHandleSys: Handle;
The NewEmptyHandleSys function initializes a new handle in the system heap by allocating a master pointer for it, but it does not allocate any memory for the handle to control. NewEmptyHandleSys sets the handle's master pointer to NIL .
Because NewEmptyHandleSys might need to call the MoreMasters procedure to allocate new master pointers, it might allocate memory. Thus, you should not call NewEmptyHandleSys at interrupt time.
When you want to allocate memory for the empty handle, use the ReallocateHandle procedure, described on ReallocateHandle .
When you are completely done with a relocatable block, call the DisposeHandle procedure to free it and its master pointer for other uses.
PROCEDURE DisposeHandle (h: Handle);
The DisposeHandle procedure releases the memory occupied by the relocatable block whose handle is h . It also frees the handle's master pointer for other uses.
After a call to DisposeHandle , all handles to the released block become invalid and should not be used again. Any subsequent calls to DisposeHandle using an invalid handle might damage the master pointer list.
Do not use DisposeHandle to dispose of a handle obtained from the Resource Manager (for example, by a previous call to GetResource ); use ReleaseResource instead. If, however, you have called DetachResource on a resource handle, you should dispose of the storage by calling DisposeHandle .
Because DisposeHandle purges memory, you should not call it at interrupt time.